C.S.Burner 🪙 ━►🔥GIT Node

Micron Document

Node / reticulum_mirror / MeshChatX / files / docs / en / plugins.md

Displaying Rendered • View raw • Download

docs/en/plugins.md dev (8f381c86) Text, 9.42 KB

Plugins

Plugins extend MeshChatX with extra tools, nav items, and background behaviour. They are capability-gated: a plugin only gets what you grant at install time.

Manage them from Settings → Plugins. Disable every packaged plugin at startup with T383838--disable-plugins or T383838MESHCHAT_DISABLE_PLUGINS=true.

What plugins can do

• Add a row on the Tools page

• Add an item in the main Navigation sidebar

• React to mesh events (announces, RNS link traffic)

• Call narrowly declared backend managers (path table, debug log, bug reports, RNS links)

• Keep a private key-value store (T383838storage: isolated)

• Optionally fetch clearnet HTTP (T383838network: fetch), still subject to Privacy mode

Plugins cannot rewrite core MeshChatX. They do not get open-ended filesystem or process control unless you opt into Sideband Python plugins (see below).

Runtimes

┌────────────────┬───────────────────────────┬─────────────────────────────────────────────────┐

│ Runtime │ Where it runs │ Trust level │

├────────────────┼───────────────────────────┼─────────────────────────────────────────────────┤

│ Frontend JS │ Browser Web Worker │ Medium. Sandboxed worker, capability grants │

│ Backend WASM │ T383838wasmtime on the server │ Medium. Fuel-metered, capability-gated host │

│ Backend Python │ In-process with MeshChatX │ High. Permission-checked in-process host │

│ Sideband T383838*.py │ In-process, flat files │ Highest. Opt-in danger switch, full host access │

└────────────────┴───────────────────────────┴─────────────────────────────────────────────────┘

A packaged plugin can ship frontend only, backend only, or both.

Install flow

T282828

Pick ZIP or .wasm file in Settings → Plugins

--> Preview (permissions, URLs, signature, findings)

--> You grant or deny each capability

--> Optional: trust a valid signer

--> Install + integrity hash stored

--> Enable

--> Frontend Worker loads (if present)

--> Backend WASM / Python activates (if present)

Invalid signatures hard-block install. Unsigned packages are allowed. Present-but-broken signatures are not.

After install, MeshChatX hashes the on-disk tree. If files change outside the app, the plugin is auto-disabled as tampered.

Bundled example: Bug Reports

T383838com.meshchatx.mcx-bugs ships with MeshChatX. It adds a Bug Reports tool for sending redacted debug logs to an T383838mcx-bugs-v1 collector, or running a collector yourself.

Layout:

T282828

mcx-bugs/

plugin.json

frontend/main.js

backend/main.py

locales/en.json

Use it as the reference package when building your own.

Manifest (T383838plugin.json)

Every packaged plugin needs a root T383838plugin.json.

T282828

Tb4b4b4{

Tff7b72"id"Tb4b4b4: Ta5d6ff"com.example.my-plugin"Tb4b4b4,

Tff7b72"version"Tb4b4b4: Ta5d6ff"1.0.0"Tb4b4b4,

Tff7b72"apiVersion"Tb4b4b4: T79c0ff1Tb4b4b4,

Tff7b72"name"Tb4b4b4: Ta5d6ff"My Plugin"Tb4b4b4,

Tff7b72"description"Tb4b4b4: Ta5d6ff"Adds a custom tool."Tb4b4b4,

Tff7b72"frontend"Tb4b4b4: Tb4b4b4{

Tff7b72"entry"Tb4b4b4: Ta5d6ff"frontend/main.js"Tb4b4b4,

Tff7b72"type"Tb4b4b4: Ta5d6ff"js"

Tb4b4b4},

Tff7b72"backend"Tb4b4b4: Tb4b4b4{

Tff7b72"entry"Tb4b4b4: Ta5d6ff"backend/main.py"Tb4b4b4,

Tff7b72"type"Tb4b4b4: Ta5d6ff"python"

Tb4b4b4},

Tff7b72"i18n"Tb4b4b4: Tb4b4b4{

Tff7b72"directory"Tb4b4b4: Ta5d6ff"locales"Tb4b4b4,

Tff7b72"defaultLocale"Tb4b4b4: Ta5d6ff"en"

Tb4b4b4},

Tff7b72"contributes"Tb4b4b4: Tb4b4b4{

Tff7b72"navItems"Tb4b4b4: Tb4b4b4[

Tb4b4b4{

Tff7b72"id"Tb4b4b4: Ta5d6ff"my-plugin"Tb4b4b4,

Tff7b72"route"Tb4b4b4: Tb4b4b4{ Tff7b72"name"Tb4b4b4: Ta5d6ff"plugin-my-plugin" Tb4b4b4},

Tff7b72"icon"Tb4b4b4: Ta5d6ff"puzzle"Tb4b4b4,

Tff7b72"labelKey"Tb4b4b4: Ta5d6ff"nav"

Tb4b4b4}

Tb4b4b4],

Tff7b72"toolsPageEntries"Tb4b4b4: Tb4b4b4[

Tb4b4b4{

Tff7b72"name"Tb4b4b4: Ta5d6ff"my-plugin"Tb4b4b4,

Tff7b72"route"Tb4b4b4: Tb4b4b4{ Tff7b72"name"Tb4b4b4: Ta5d6ff"plugin-my-plugin" Tb4b4b4},

Tff7b72"icon"Tb4b4b4: Ta5d6ff"puzzle"Tb4b4b4,

Tff7b72"titleKey"Tb4b4b4: Ta5d6ff"title"Tb4b4b4,

Tff7b72"descriptionKey"Tb4b4b4: Ta5d6ff"description"

Tb4b4b4}

Tb4b4b4]

Tb4b4b4},

Tff7b72"permissions"Tb4b4b4: Tb4b4b4{

Tff7b72"hooks"Tb4b4b4: Tb4b4b4[Ta5d6ff"announce.received"Tb4b4b4],

Tff7b72"managers"Tb4b4b4: Tb4b4b4[Ta5d6ff"destinationPath.read"Tb4b4b4],

Tff7b72"storage"Tb4b4b4: Ta5d6ff"isolated"Tb4b4b4,

Tff7b72"network"Tb4b4b4: Ta5d6ff"none"

Tb4b4b4}

Notes:

• T383838id is reverse-DNS style and must stay stable across versions

• T383838apiVersion is currently T3838381

• Plugin strings live in the plugin bundle (T383838locales/{locale}.json), not core T383838en.json

• T383838contributes wires UI slots through the frontend registries

Permissions

Nothing is available unless it is declared in the manifest and granted in the install dialog.

Hooks

┌───────────────────┬─────────────────────────────────────────────────────────┐

│ Hook │ When it fires │

├───────────────────┼─────────────────────────────────────────────────────────┤

│ T383838announce.received │ A Reticulum announce arrives │

│ T383838rns.link.event │ Generic RNS Link traffic (T383838packet_received, T383838link_closed) │

└───────────────────┴─────────────────────────────────────────────────────────┘

Hook events reach the UI as WebSocket T383838plugin.event frames, then into the plugin Worker.

Managers

┌──────────────────────┬───────────────────────────────┐

│ Manager │ Purpose │

├──────────────────────┼───────────────────────────────┤

│ T383838destinationPath.read │ Read the Reticulum path table │

│ T383838debugLog.read │ Read redacted debug logs │

│ T383838bugReport.* │ Bug report / collector APIs │

│ T383838rnsLink.open │ Open or reuse an RNS link │

│ T383838rnsLink.identify │ Identify on a cached link │

│ T383838rnsLink.request │ Request/response on a link │

│ T383838rnsLink.send │ Send a raw link packet │

│ T383838rnsLink.close │ Tear down a cached link │

└──────────────────────┴───────────────────────────────┘

Call managers from a plugin with T383838POST /api/v1/plugins/{id}/invoke and T383838method: "callManager". Details for the link transport are in RNS Link API.

Storage and network

┌───────────────────┬───────────────────────────────────────────────────────────────────────┐

│ Permission │ Effect │

├───────────────────┼───────────────────────────────────────────────────────────────────────┤

│ T383838storage: isolated │ Private key-value store in the MeshChatX database │

│ T383838storage: none │ No plugin storage │

│ T383838network: fetch │ Outbound HTTP allowed (still blocked by Privacy mode when that is on) │

│ T383838network: none │ No clearnet fetch │

└───────────────────┴───────────────────────────────────────────────────────────────────────┘

Install preview also scans plugin files for external T383838http:// / T383838https:// URLs and shows them before you grant network access.

How a frontend plugin runs

T282828

Settings enable plugin

--> PluginHost loads /api/v1/plugins

--> Fetch frontend entry as text

--> Spawn pluginWorker.js (module Worker)

--> Register nav / tools contributions

--> Subscribe to plugin.event on /ws (if hooks granted)

--> Worker may invoke backend via /api/v1/plugins/{id}/invoke

The Worker talks to the host with typed messages (T383838init, T383838event, T383838request). The host never gives the Worker a raw privileged API.

How a backend plugin runs

T282828

Enable plugin

+--> type: wasm --> load into wasmtime, fuel + host caps

+--> type: python --> import entry, call activate(host)

--> Hooks fan out from PluginManager

--> invoke(method, args) for RPC from the UI Worker

Python host surface (permission-checked):

• T383838host.log(message)

• T383838host.call_manager(capability, args)

• T383838host.storage_get(key) / T383838host.storage_set(key, value)

• T383838host.network_fetch_allowed()

Packaging and signing

Distribute as:

1. ZIP with T383838plugin.json and assets

2. WASM bundle (single T383838.wasm with embedded manifest / files / optional signature)

Signature file for ZIP/dir packages: T383838meshchatx.plugin.rsg

WASM custom sections:

T282828

meshchatx.plugin --> embedded plugin.json

meshchatx.files --> embedded text assets

meshchatx.signature --> RSG over payload without this section

Canonical ZIP signing uses sorted paths and fixed 1980-01-01 mtimes. The signature file itself is excluded from the signed payload.

Sign and verify with:

T282828

python3 scripts/sign-plugin.py sign-dir ./my-plugin --identity <rnid>

python3 scripts/sign-plugin.py verify-dir ./my-plugin

python3 scripts/sign-plugin.py sign-zip ./my-plugin.zip --identity <rnid>

python3 scripts/sign-plugin.py sign-wasm ./plugin.wasm --identity <rnid>

python3 scripts/sign-plugin.py sign-py ./legacy_plugin.py --identity <rnid>

Trust status in the UI:

T282828

No .rsg present

--> Unsigned (install allowed)

Valid .rsg, signer unknown

--> Signed (you can add to Trusted Publishers)

Valid .rsg, signer in Trusted Publishers

--> Trusted

Broken / mismatched .rsg

--> Invalid (install blocked)

Sideband-compatible plugins

Legacy Sideband-style flat T383838*.py files are separate from packaged ZIP/WASM plugins.

T282828

Settings → Plugins → Sideband

--> Confirm danger prompt

--> Set directory of *.py files

--> Optional filename.py.rsg next to each script

--> Reload

These run in-process with full host access. They are not ZIP-permission gated. Keep the master switch off unless you trust every file in that directory.

Operator tips

• Prefer signed packages from publishers you added yourself

• Deny T383838network: fetch unless the plugin needs clearnet HTTP

• Prefer WASM backends over Python when you can

• Use T383838--disable-plugins when diagnosing weird UI or backend behaviour

• Treat Sideband plugins like running arbitrary local scripts